home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / misc / robodoc.lha / ROBODoc.doc < prev    next >
Encoding:
Text File  |  1992-09-02  |  10.0 KB  |  330 lines
  1. ===============================================================================
  2.  
  3.                 ROBODoc v0.92
  4.  
  5. -------------------------------------------------------------------------------
  6.  
  7.     (c) 1995, by Jacco van Weert, Maverick Software Development
  8.     email: weertj@euronet.nl
  9.  
  10.     ROBODoc documentation for the;
  11.       Amiga computers.
  12.       DEC Alpha systems.
  13.       DEC VAX systems.
  14.  
  15.     New versions of ROBODoc are made available on AmiNet.
  16.  
  17.     or
  18.  
  19.     On the Amigoline BBS;
  20.         Tel:    +31-8347-84968    (International)
  21.         Tel:    08347-84968    (From the Netherlands)
  22.  
  23. ===============================================================================
  24.  
  25.  
  26.  
  27.                 Preface
  28.                 -------
  29.  
  30. The complete ROBODoc archive is copyrighted by Jacco van Weert,
  31. Maverick Software Development.
  32.  
  33. ROBODoc can be freely distributed on FREEWARE base as long as all files remains
  34. in there original state, no files may be added to the archive, and also no files
  35. may be excluded.
  36.  
  37. This software is provided on an "AS IS" basis without warranty of any kind. The
  38. author is not responsible for any damage caused by using this software.
  39.  
  40.  
  41.                 Hardware requirements
  42.                 ---------------------
  43.  
  44. Amiga version:
  45.     ROBODoc runs well on every Amiga, no special requirements are necessary.
  46.  
  47. DEC Alpha/VAX:
  48.     ROBODoc v0.92 has been tested on a DEC Alpha system using OpenVMS-AXP 
  49.     v1.5, but in general terms there should be no problem to run this
  50.     program on other systems. It is a general C program.
  51.  
  52.  
  53.                 Introduction
  54.                 ------------
  55.  
  56. ROBODoc is based on the AutoDocs program written some time ago by Commodore.
  57. The idea is to include for every procedure/function a standard header
  58. containing all sorts of information about that procedure/function.
  59. ROBODoc will extract those headers from the source file and put them in a
  60. autodocs-file. This autodocs-file can be written in three different formats;
  61.  
  62. - Normal format;
  63.     The autodocs-file is just a plain ASCII text-file, this file is very
  64.     closely related to the one that the original AutoDocs program would
  65.     generated.
  66.  
  67. - HTML format;
  68.     The autodocs-file will be written as a HTML-file (HyperText Markup
  69.     Language), this format is used on the WWW-Internet. By using a
  70.     Mosiac/Netscape program you view the documentation. In v0.5 of
  71.     ROBODoc this option will produce a very basic HTML-file, new versions
  72.     will produce a far more better result.
  73.  
  74. - AmigaGuide format;
  75.     This is a format used on the Amiga computers to view in a HyperText
  76.     way a text-file. The AmigaGuide (OS3.0 tags are supported) program
  77.     is necessary to view the resulting autodocs-file.
  78.  
  79.  
  80.                 This Version
  81.                 ------------
  82.  
  83. As you probably noticed this version has still a beta-number (v0.8). This
  84. means not that the program is not finished, but it means that I have not
  85. implemented all the functions I wish to. And of course the program could
  86. still have some bugs.
  87.  
  88.  
  89.                 Procedure/Function Header
  90.                 -------------------------
  91.  
  92. We shall now discuss the general format of a procedure/function header.
  93. Full discussion of the header can be found in AutoDocs-documentation, this
  94. is a brief explanation of the header and the ROBODoc special items.
  95.  
  96. ROBODoc handles three different type of headers;
  97.  
  98. - MainProgram header (optional);
  99.     These headers are placed at the start of a program and containing
  100.     some general information about the program. These where not
  101.     available in the original AutoDocs program.
  102.  
  103. - Normal header;
  104.     The normal header, available to the general public.
  105.  
  106. - Internal header;
  107.     The internal header not available to the general public, mainly
  108.     used by the programmer him/herself.
  109.  
  110.  
  111.  
  112.                 MainProgram header
  113.                 ------------------
  114.  
  115. We now discuss an example of a MainProgram header. The following header was
  116. taken from the original ROBODoc program.
  117.  
  118. /****h* AUTODOC/ROBODoc ***************************************************
  119. *
  120. *    NAME
  121. *      ROBODoc -- AutoDoc formatter
  122. *
  123. *    COPYRIGHT
  124. *      Maverick Software Development
  125. *      This software is public domain and can be freely redistributed as
  126. *      long as it is in it's original state.
  127. *
  128. *    FUNCTION
  129. *      ROBODoc is indented as a replacement for the original AutoDocs program
  130. *      ROBODoc will extract from a source file the procedure comment headers
  131. *      and put them in a seperate documentation file. There are basically
  132. *      three different file outputs, Basic (Normal text based)/ HTML
  133. *      Markup langauge mainly used on the Internet thus the files can be viewed
  134. *      with a normal Mosaic viewer/ and finally AmigaGuide format, this format
  135. *      can be viewed by an AmigaGuide program (AMIGA ONLY).
  136. *
  137. *    AUTHOR
  138. *      Jacco van Weert
  139. *
  140. *    CREATION DATE
  141. *      20-Dec-94
  142. *
  143. *    MODIFICATION HISTORY
  144. *      25-Jan-94    -    v0.92: First version
  145. *
  146. *    NOTES
  147. *      None  
  148. *
  149. ****************************************************************************
  150. */
  151.  
  152. Because the program was written in C the header is in this form, in assembler
  153. or other langauges it would look a little bit different.
  154. MOST IMPORTANT is that the first line of the header must be reconized by the
  155. ROBODoc program. Therefore is the following rule;
  156.  
  157. The first character is not important.
  158. The next 4 characters must be asterics '*'.
  159. The next character defines the header type;
  160.     'h' = MainProgram
  161.     '*' = Normal header
  162.     'i' = Internal header
  163. Then follows 1 asteric '*' and 1 space.
  164. After this follows the [module name]/[procedure name]
  165.  
  166. Example:
  167.  
  168. In C    ->    /****h* programs/greatprogram.library *********
  169.     or    /****** greatprogram.library/program_init ******
  170.     or    /****i* greatprogram.library/very_secret *******
  171. In Assembler
  172.     ->    ;****h* programs/greatprogram.library ********
  173.     ->    ******* greatprogram.library/program_init ******
  174.     ->    *****i* greatprogram.library/internal_affairs *****
  175.  
  176. The header ends with a following line;
  177.  
  178. *********..etc
  179. or
  180. ;********..etc
  181. or
  182. %********..etc
  183.  
  184. In general the first character of the line is not important.
  185.  
  186.  
  187. But now back to the MainProgram header, it has the following items;
  188.  
  189. NAME            - The name of the program.
  190. COPYRIGHT        - The copyright note.
  191. FUNCTION        - The general function of the program.
  192. AUTHOR            - The author of the program (very important :)
  193. CREATION DATE        - When did you started?
  194. MODIFICATION HISTORY    - All the changed made to the program.
  195. NOTES            - General notes.
  196.  
  197. Important is that all items have the same indent. It is not necessary
  198. to include all items, ROBODoc will add the missing items.
  199.  
  200.  
  201.  
  202.                 Normal header
  203.                 -------------
  204.  
  205. The normal header differs not from the original AutoDoc header which we
  206. will give here;
  207.  
  208. /****** financial.library/StealMoney ******************************************
  209. * 
  210. *   NAME    
  211. *     StealMoney -- Steal money from the Federal Reserve Bank. (V77)
  212. * 
  213. *   SYNOPSIS
  214. *    error = StealMoney( userName,amount,destAccount,falseTrail )
  215. *    D0,Z                D0       D1.W    A0         [A1]
  216. *
  217. *    BYTE StealMoney
  218. *         ( STRPTR,UWORD,struct AccountSpec *,struct falseTrail *);
  219. *
  220. *   FUNCTION
  221. *    Transfer money from the Federal Reserve Bank into the specified
  222. *    interest-earning checking account.  No records of the transaction
  223. *    will be retained.
  224. * 
  225. *   INPUTS
  226. *     userName      - name to make the transaction under.  Popular favorites
  227. *                    include "Ronald Reagan" and "Mohamar Quadaffi".
  228. *    amount        - Number of dollars to transfer (in thousands).
  229. *    destAccount   - A filled-in AccountSpec structure detailing the
  230. *                    destination account (see financial/accounts.h).
  231. *            If NULL, a second Great Depression will be triggered.
  232. *    falseTrail    - If the DA_FALSETRAIL bit is set in the destAccount,
  233. *            a falseTrail structure must be provided.
  234. *    
  235. *   RESULT
  236. *     error - zero for success, else an error code is returned (see
  237. *            financial/errors.h).  The Z condition code is guaranteed.
  238. * 
  239. *   EXAMPLE
  240. *    Federal regulations prohibit a demonstration of this function. 
  241. *
  242. *   NOTES
  243. *    Do not run on Tuesdays!
  244. *
  245. *   BUGS
  246. *     Before V88, this function would occasionally print the address and
  247. *    home phone number of the caller on local police 976 terminals.
  248. *    We are confident that this problem has been resolved.
  249. * 
  250. *   SEE ALSO
  251. *     CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
  252. *    financial/misc.h
  253. * 
  254. *****************************************************************************/
  255.  
  256. Again it is not necessary to include all items.
  257.  
  258.  
  259.                 Internal header
  260.                 ---------------
  261.  
  262. The same as the Normal header, except the internal header starts with the line
  263. /****i* or ;****i* or *****i* or......
  264.  
  265.  
  266.                 Usage of ROBODoc
  267.                 ----------------
  268.  
  269. To list the arguments needed by ROBODoc just enter ROBODoc or ROBODoc ?
  270. To following message will be printed;
  271.  
  272. ROBODoc v0.92, autodocs formatter
  273. ==============================================
  274. (c) 25-1-95, Maverick Software Development
  275. Written by J.v.Weert, email: weertj@euronet.nl
  276. FORMAT
  277.   ROBODoc filename docfilename [HTML] [GUIDE] [INTERNAL] [SORT] [TOC] [XREF]
  278.  
  279. The parameters;
  280.  
  281.     filename    = The source code filename.
  282.     docfilename    = The name of the documentation file,
  283.               which will be created.
  284.     HTML        = The documentation will be in HTML format.
  285.     GUIDE        = The documentation will be in AmigaGuide format.
  286.     INTERNAL    = The internal headers are also included.
  287.     SORT        = The procedures will be sorted.
  288.     TOC        = A table of contents will be added. TOC will be
  289.               automatically set when HTML or GUIDE is set.
  290.     XREF        = This option will enable the AutoXREF mode:
  291.               In the current version it will only references the
  292.               procedures and functions used within the same
  293.               document.
  294.  
  295.                 CONCLUSION
  296.                 ----------
  297.  
  298. Remember that this is a pre-release, and a lot of options I want to
  299. include are not included in this version (for example an automatic XREF that
  300. will create references across many different files).
  301. I release this to get (hopefully) some feedback about the functions and
  302. options which are wanted, but only a message that you use or want to use
  303. ROBODoc is enough.
  304.  
  305.  
  306.                 SUGGESTIONS EN BUGS
  307.                 -------------------
  308.  
  309. Suggestions and bug reports (please use the included Bug-report form) can
  310. be send to;
  311.  
  312.     Email:    weertj@euronet.nl
  313.  
  314.     or
  315.  
  316.     Maverick Software Development, T.a.v. J.v.Weert
  317.     Haverdreef 131,
  318.     7006 LH, Doetinchem.
  319.     The Netherlands.
  320.  
  321.  
  322.                 __  __________
  323.              __/  \/         /   weertj@euronet.nl
  324.           __/  \__/ Maverick
  325.          /  \__/  \ Software
  326.          \__/  \__/ Development
  327.          _______________/        slothoub@xs4all.nl
  328.  
  329.  
  330.